1.5 Common issues with jfinal-undertow

1. Support for Hot Reloading in IDEA

jfinal undertow triggers hot reloading by monitoring modifications to .class files under the target/classes directory.

Eclipse has an auto-compile feature which automatically compiles and updates the related .class files in target/classes when the Java source code file is saved. So, by default, Eclipse supports hot reloading. Make sure to enable the auto-compile option in Eclipse, as shown in the following image:

However, IDEA does not support auto-compilation by default. Therefore, the .class files in target/classes can't be updated timely, and IDEA doesn't support hot reloading. You may need to find methods online to enable auto-compilation in IDEA. Here's a link that provides a method to trigger compilation using a shortcut for reference:

Link to Guide (opens new window)

In addition, an older jfinal official document also provided a method:

Link to jfinal Guide (opens new window)

Lastly, remember to set undertow.devMode to true to support hot reloading. Refer to previous sections for configuration details.

2. Incorrect Template File Path in IDEA

In IDEA, if you open the project directory directly or import a maven project through the pom.xml file, the template file path might be incorrect. The correct import method is shown in the images provided. Ensure that you select "import project" and not "Open". If a project has been imported once using the correct method, IDEA will generate various configuration files, and thereafter opening the project using "Open" won't be an issue.

3. Maven Multi-Module Project Startup Error

If a multi-module maven project encounters an error indicating that the template is not found during startup, it's due to the working directory in IDEA multi-modules being set to one directory above the current module during project startup. Therefore, the default undertow.resourcePath configuration value src/main/webapp is incorrect. The correct path should include the current module's name, e.g., undertow.resourcePath = [module_name]/src/main/webapp, src/main/webapp. This configuration supports both IDEA and Eclipse, and is backward compatible with both development tools.

Related Sharing (opens new window) Related Article (opens new window)

4. Type Conversion Exception, Subclass Objects Can't Be Assigned to Base Class Variables

If you encounter a type conversion exception (java.lang.ClassCastException) or a subclass object can't be assigned to a base class variable, this can be resolved by configuring hotSwapClassPrefix.

Additional exceptions related to this problem include java.lang.VerifyError: Bad type on operand stack and java.lang.IncompatibleClassChangeError.

For instance, if the class causing the conversion exception is "com.abc.UserService", the solution would be:

UndertowServer.create(MyApp.class)
    .addHotSwapClassPrefix("com.abc.")
    .start();

This means that jfinal undertow by default only supports hot reloading for classes under target/classes and for jfinal itself. Therefore, if your class file is in a jar package and needs to be hot reloaded, you need to add it as a hot reload class using the method above.

In most cases, the class files in your project under target/classes are the ones that need to be hot reloaded, so there won't be any issues.

5. Shiro Hot Reloading Issue

jfinal undertow currently does not support hot reloading for shiro. You can use it by setting undertow.devMode=false, but it won't support hot reloading.

6. Unable to Access When Deployed on External Network Servers

For security reasons, early versions of jfinal undertow had undertow.host default configured as localhost. If you can't access it from an external network server, use the following configuration:

undertow.host=0.0.0.0

If you still can't access after adding the above configuration, check if the relevant port number is open (assuming you're using Alibaba Cloud).

7. Issues Using Scripts

The jfinal official jfinal.sh and jfinal.bat script files contain detailed usage instructions. Generally, there won't be issues if you follow the instructions.

However, a peculiar issue you might encounter is if you create a script file yourself and even if you copy content from the jfinal official script, it just doesn't work. This could be due to the line ending characters in the script file. For Linux and Mac, the line ending character must be '\n', while for Windows it must be "\r\n".

To check the line ending character of the script file, first open a Java source code file in Eclipse, then click the "Show Whitespace Characters" icon in the toolbar. Afterward, open the script file in Eclipse, and the line ending character will be displayed at the end of each line. A single character indicates '\n', otherwise, it's '\r\n'.

Note that this issue is unrelated to jfinal; it's a restriction of the operating system.

Important: Recently, some users found a new reason for the script startup failure. The reason is that the jetty dependency was not removed from pom.xml, leading to the exception: java.lang.NoClassDefFoundError: com/jfinal/config/JFinalConfig. Removing the jetty dependency can resolve this.

8. Issues with JSP Support

To enhance application security, newer versions of jfinal by default do not allow direct access to .jsp files. This means you can't directly input a .jsp filename in the browser's address bar to access a JSP file. However, you can access the JSP file using renderJsp(xxx.jsp). If you indeed need direct access to JSP files, you need the following configuration:

public void configConstant(Constants me) {
    me.setDenyAccessJsp(false);
}

To support JSP functionality in jfinal undertow, a similar configuration is needed:

UndertowServer.create(DemoConfig.class)
   .configWeb(wb -> {
      wb.getDeploymentInfo().addServlet(JspServletBuilder.createServlet("Default Jsp Servlet", "*.jsp"));
 
      HashMap<String, TagLibraryInfo> tagLibraryInfo = new HashMap<>();
      JspServletBuilder.setupDeployment(wb.getDeploymentInfo(), new HashMap<>(),
      tagLibraryInfo, new HackInstanceManager());
   })
   .start();

For more information, you can refer to the following resources:

Resource 1 (opens new window) Resource 2 (opens new window) GitHub Repo (opens new window)

9. Issues with mp4 Not Playing, xls Not Downloading, etc. due to Incorrect contentType

You might need to add a configuration similar to the following:

UndertowServer
  .create()
  .configWeb(
      builder -> {
          MimeMapping xlsMimeMapping = new MimeMapping("xls","application/vnd.ms-excel");
          builder.getDeploymentInfo().addMimeMapping(xlsMimeMapping);
      })
  .start();

The above is an example for xls files. For mp4 files, a similar configuration is needed. For related references, see:

Reference 1 (opens new window) Reference 2 (opens new window)